HTML5 的自定義屬性

TLDR

• HTML5 規範允許使用 data-* 作為自定義屬性，不會觸發無效屬性警告。
• JavaScript 使用 dataset API 存取，屬性名稱會自動轉換為小駝峰命名法（lower camel case）。
• jQuery 的 data() 方法並非直接操作 DOM 屬性，而是將資料存放在 jQuery.cache 中。
• dataset 與 jQuery data() 機制完全不同，兩者不可混用。
• 建議優先使用 dataset（現代瀏覽器已全面支援），若需處理 JSON 格式或舊版瀏覽器相容性，則可考慮 jQuery data()。

---

HTML5 自定義屬性規範

在 HTML5 規範中，開發者可以使用 data-* 開頭的屬性來儲存自定義資料。這類屬性符合規範，不會在瀏覽器開發者工具中產生無效屬性警告。

注意：這些自定義屬性屬於 HTML Attribute，並不會自動同步至 DOM Property。因此，不能使用 prop() 或直接透過 DOM 物件屬性進行存取。

---

JavaScript 的 dataset API

當網頁執行時，HTML 元素上的 data-* 屬性會被轉換為 DOMStringMap 物件，並儲存在 DOM 物件的 dataset 屬性中。

屬性名稱轉換規則

JavaScript 存取時，屬性名稱會經過以下轉換：

1. 移除 data- 前綴。
2. 移除剩餘名稱中的 -。
3. 將 - 後的字母轉為大寫（小駝峰命名法）。

範例： 若 HTML 為 <div data-cloudy-wing="value"></div>，JavaScript 存取方式如下：

const element = document.querySelector('div');
console.log(element.dataset.cloudyWing); // 輸出: "value"

---

jQuery 的 data() 方法

jQuery 的 data() 方法與 JavaScript 的 dataset 機制不同。data() 是將資料存放在 jQuery.cache 中，而非直接操作 DOM 屬性。

核心特性與踩雷紀錄

• 資料同步：使用 data() 設定值後，不會回寫至 HTML Tag。
• 型別轉換：data() 會自動判斷屬性值型別。例如，若屬性值為 JSON 字串，data() 可自動轉換為 Object。
• JSON 格式要求：若要在 HTML 中定義 JSON，必須使用單引號包覆字串，內部屬性使用雙引號。
  • 正確範例：data-wing='{"name": "wing"}'
• 版本差異：在 jQuery 1.7 以前，數值 012.050 會被視為數字 12.05；1.8 以後則統一視為字串 012.050。

存取建議

• 簡單屬性（如 disabled）：使用 prop()。
• 自定義屬性：使用 data()。
• 一般屬性：使用 attr()。

WARNING

jQuery.data(element, key) 為底層方法，無法正確取得 HTML 標籤上的 data-* 屬性，建議直接使用 .data(key)。

---

dataset 與 jQuery data() 的比較

兩者機制不同，無法混用。dataset 每次存取都會直接操作 DOM，而 data() 在初始化後會改從 jQuery.cache 讀取。

特性	JavaScript dataset	jQuery data()
儲存位置	DOM 屬性	jQuery.cache
資料型別	僅限字串	自動轉換 (含 JSON)
瀏覽器支援	現代瀏覽器均支援	支援舊版瀏覽器 (如 IE)

TIP

隨著現代前端框架（如 Vue, React）的普及，直接操作 DOM 的需求已大幅減少，建議根據專案環境選擇合適的存取方式。

異動歷程

1. 2024-03-09

   • 初版文件建立。